<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>48.4. View Helpers</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="prev" href="zend.view.scripts.html" title="48.3. View Scripts">
<link rel="next" href="zend.view.abstract.html" title="48.5. Zend_View_Abstract">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.view.helpers.html#zend.view.helpers.initial" title="48.4.1. Initial Helpers">
<link rel="subsection" href="zend.view.helpers.html#zend.view.helpers.paths" title="48.4.2. Helper Paths">
<link rel="subsection" href="zend.view.helpers.html#zend.view.helpers.custom" title="48.4.3. Writing Custom Helpers">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">48.4. View Helpers</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.view.scripts.html">Prev</a> </td>
<th width="60%" align="center">Chapter 48. Zend_View</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.view.abstract.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.view.helpers"></a>48.4. View Helpers</h2></div></div></div>
<p>
        In your view scripts, often it is necessary to perform certain
        complex functions over and over: e.g., formatting a date,
        generating form elements, or displaying action links.  You can
        use helper classes to perform these behaviors for you.
    </p>
<p>
        A helper is simply a class. Let's say we want a helper named 'fooBar'.
        By default, the class is prefixed with <code class="code">'Zend_View_Helper_'</code>
        (you can specify a custom prefix when setting a helper path), and the
        last segment of the class name is the helper name; this segment should
        be TitleCapped; the full class name is then:
        <code class="code">Zend_View_Helper_FooBar</code>. This class should contain at the
        minimum a single method, named after the helper, and camelCased:
        <code class="code">fooBar()</code>.
    </p>
<div class="note"><table border="0" summary="Note: Watch the Case">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Watch the Case</th>
</tr>
<tr><td align="left" valign="top"><p>
            Helper names are always camelCased, i.e., they never begin with an
            uppercase character. The class name itself is MixedCased, but the
            method that is actually executed is camelCased.
        </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note: Default Helper Path">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Default Helper Path</th>
</tr>
<tr><td align="left" valign="top"><p>
            The default helper path always points to the Zend Framework view
            helpers, i.e., 'Zend/View/Helper/'. Even if you call
            <code class="code">setHelperPath()</code> to overwrite the existing paths, this
            path will be set to ensure the default helpers work.
        </p></td></tr>
</table></div>
<p>
        To use a helper in your view script, call it using
        <code class="code">$this-&gt;helperName()</code>. Behind the scenes,
        <code class="code">Zend_View</code> will load the
        <code class="code">Zend_View_Helper_HelperName</code> class, create an object
        instance of it, and call its <code class="code">helperName()</code> method.  The
        object instance is persistent within the <code class="code">Zend_View</code>
        instance, and is reused for all future calls to
        <code class="code">$this-&gt;helperName()</code>.
    </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.view.helpers.initial"></a>48.4.1. Initial Helpers</h3></div></div></div>
<p>
            <code class="code">Zend_View</code> comes with an initial set of helper classes,
            most of which relate to form element generation and perform
            the appropriate output escaping automatically. In addition, there
            are helpers for creating route-based URLs and HTML lists, as well as
            declaring variables. The currently shipped helpers include:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                <code class="code">declareVars():</code> Primarily for use when using
                <code class="code">strictVars()</code>, this helper can be used to declare
                template variables that may or may not already be set in the
                view object, as well as to set default values.  Arrays passed as
                arguments to the method will be used to set default values;
                otherwise, if the variable does not exist, it is set to an empty
                string.
            </p></li>
<li><p>
                <code class="code">fieldset($name, $content, $attribs):</code> Creates an
                XHTML fieldset. If <code class="code">$attribs</code> contains a 'legend'
                key, that value will be used for the fieldset legend. The
                fieldset will surround the <code class="code">$content</code> as provided to
                the helper.
            </p></li>
<li><p>
                <code class="code">form($name, $attribs, $content):</code> Generates an XHTML
                form. All <code class="code">$attribs</code> are escaped and rendered as
                XHTML attributes of the form tag. If <code class="code">$content</code> is
                present and not a boolean false, then that content is rendered
                within the start and close form tags; if <code class="code">$content</code>
                is a boolean false (the default), only the opening form tag is
                generated.
            </p></li>
<li><p>
                <code class="code">formButton($name, $value, $attribs):</code> Creates an
                &lt;button /&gt; element.
            </p></li>
<li>
<p>
                    <code class="code">formCheckbox($name, $value, $attribs,
                        $options):</code> Creates an &lt;input type="checkbox"
                    /&gt; element.  
                </p>
<p>
                    By default, when no $value is provided and no $options are
                    present, '0' is assumed to be the unchecked value, and '1'
                    the checked value. If a $value is passed, but no $options
                    are present, the checked value is assumed to be the value
                    passed.
                </p>
<p>
                    $options should be an array. If the array is indexed, the
                    first value is the checked value, and the second the
                    unchecked value; all other values are ignored. You may also
                    pass an associative array with the keys 'checked' and
                    'unChecked'.
                </p>
<p>
                    If $options has been passed, if $value matches the checked
                    value, then the element will be marked as checked. You may
                    also mark the element as checked or unchecked by passing a
                    boolean value for the attribute 'checked'.
                </p>
<p>
                    The above is probably best summed up with some examples:
                </p>
<pre class="programlisting">&lt;?php
// '1' and '0' as checked/unchecked options; not checked
echo $this-&gt;formCheckbox('foo');

// '1' and '0' as checked/unchecked options; checked
echo $this-&gt;formCheckbox('foo', null, array('checked' =&gt; true));

// 'bar' and '0' as checked/unchecked options; not checked 
echo $this-&gt;formCheckbox('foo', 'bar');

// 'bar' and '0' as checked/unchecked options; checked 
echo $this-&gt;formCheckbox('foo', 'bar', array('checked' =&gt; true));

// 'bar' and 'baz' as checked/unchecked options; unchecked 
echo $this-&gt;formCheckbox('foo', null, null, array('bar', 'baz');

// 'bar' and 'baz' as checked/unchecked options; unchecked 
echo $this-&gt;formCheckbox('foo', null, null, array(
    'checked' =&gt; 'bar', 
    'unChecked' =&gt; 'baz'
));

// 'bar' and 'baz' as checked/unchecked options; checked 
echo $this-&gt;formCheckbox('foo', 'bar', null, array('bar', 'baz');
echo $this-&gt;formCheckbox('foo', null, array('checked' =&gt; true), array('bar', 'baz');

// 'bar' and 'baz' as checked/unchecked options; unchecked 
echo $this-&gt;formCheckbox('foo', 'baz', null, array('bar', 'baz');
echo $this-&gt;formCheckbox('foo', null, array('checked' =&gt; false), array('bar', 'baz');
</pre>
<p>
                    In all cases, the markup prepends a hidden element with the
                    unchecked value; this way, if the value is unchecked, you
                    will still get a valid value returned to your form.
                </p>
</li>
<li>
<p>
                    <code class="code">formErrors($errors, $options):</code> Generates an
                    XHTML unordered list to show errors. <code class="code">$errors</code>
                    should be a string or an array of strings;
                    <code class="code">$options</code> should be any attributes you want
                    placed in the opening list tag.
                </p>
<p>
                    You can specify alternate opening, closing, and separator
                    content when rendering the errors by calling several methods
                    on the helper:
                </p>
<div class="itemizedlist"><ul type="circle">
<li><p>
                            <code class="code">setElementStart($string)</code>; default is
                            '&lt;ul class="errors"%s"&gt;&lt;li&gt;', where %s
                            is replaced with the attributes as specified in
                            <code class="code">$options</code>.
                    </p></li>
<li><p>
                            <code class="code">setElementSeparator($string)</code>; default
                            is '&lt;/li&gt;&lt;li&gt;'.
                    </p></li>
<li><p>
                            <code class="code">setElementEnd($string)</code>; default is
                            '&lt;/li&gt;&lt;/ul&gt;'.
                    </p></li>
</ul></div>
</li>
<li><p>
                <code class="code">formFile($name, $value, $attribs):</code> Creates an
                &lt;input type="file" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formHidden($name, $value, $attribs):</code> Creates an
                &lt;input type="hidden" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formLabel($name, $value, $attribs):</code> Creates a
                &lt;label&gt; element, setting the <code class="code">for</code> attribute to
                <code class="code">$name</code>, and the actual label text to
                <code class="code">$value</code>. If <code class="code">disable</code> is passed in
                <code class="code">attribs</code>, nothing will be returned.
            </p></li>
<li><p>
                <code class="code">formMultiCheckbox($name, $value, $attribs, $options,
                    $listsep):</code> Creates a list of checkboxes.
                <code class="code">$options</code> should be an associative array, and may be
                arbitrarily deep. <code class="code">$value</code> may be a single value or
                an array of selected values that match the keys in the
                <code class="code">$options</code> array. <code class="code">$listsep</code> is an HTML
                break ("&lt;br /&gt;") by default. By default, this element is
                treated as an array; all checkboxes share the same name, and are
                submitted as an array.
            </p></li>
<li><p>
                <code class="code">formPassword($name, $value, $attribs):</code> Creates an
                &lt;input type="password" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formRadio($name, $value, $attribs, $options):</code>
                Creates a series of &lt;input type="radio" /&gt; elements, one
                for each of the $options elements.  In the $options array, the
                element key is the radio value, and the element value is the
                radio label.  The $value radio will be preselected for you.
            </p></li>
<li><p>
                <code class="code">formReset($name, $value, $attribs):</code> Creates an
                &lt;input type="reset" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formSelect($name, $value, $attribs, $options):</code>
                Creates a &lt;select&gt;...&lt;/select&gt; block, with one
                &lt;option&gt;one for each of the $options elements.  In the
                $options array, the element key is the option value, and the
                element value is the option label.  The $value option(s) will be
                preselected for you.
            </p></li>
<li><p>
                <code class="code">formSubmit($name, $value, $attribs):</code> Creates an
                &lt;input type="submit" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formText($name, $value, $attribs):</code> Creates an
                &lt;input type="text" /&gt; element.
            </p></li>
<li><p>
                <code class="code">formTextarea($name, $value, $attribs):</code> Creates a
                &lt;textarea&gt;...&lt;/textarea&gt; block.
            </p></li>
<li><p>
                <code class="code">url($urlOptions, $name, $reset):</code> Creates a URL
                string based on a named route. <code class="code">$urlOptions</code> should
                be an associative array of key/value pairs used by the
                particular route.
            </p></li>
<li><p>
                <code class="code">htmlList($items, $ordered, $attribs, $escape):</code> generates
                unordered and ordered lists based on the <code class="code">$items</code>
                passed to it. If <code class="code">$items</code> is a multidimensional
                array, a nested list will be built. If the <code class="code">$escape</code>
                flag is true (default), individual items will be escaped using
                the view objects registered escaping mechanisms; pass a false
                value if you want to allow markup in your lists.
            </p></li>
</ul></div>
<p>
            Using these in your view scripts is very easy, here is an example.
            Note that you all you need to do is call them; they will load
            and instantiate themselves as they are needed.
        </p>
<pre class="programlisting">&lt;?php
// inside your view script, $this refers to the Zend_View instance.
//
// say that you have already assigned a series of select options under
// the name $countries as array('us' =&gt; 'United States', 'il' =&gt;
// 'Israel', 'de' =&gt; 'Germany').
?&gt;
&lt;form action="action.php" method="post"&gt;
    &lt;p&gt;&lt;label&gt;Your Email:
        &lt;?php echo $this-&gt;formText('email', 'you@example.com', array('size' =&gt; 32)) ?&gt;
    &lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;Your Country:
        &lt;?php echo $this-&gt;formSelect('country', 'us', null, $this-&gt;countries) ?&gt;
    &lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;Would you like to opt in?
        &lt;?php echo $this-&gt;formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?&gt;
    &lt;/label&gt;&lt;/p&gt;
&lt;/form&gt;
        </pre>
<p>
            The resulting output from the view script will look something like this:
        </p>
<pre class="programlisting">&lt;form action="action.php" method="post"&gt;
    &lt;p&gt;&lt;label&gt;Your Email:
        &lt;input type="text" name="email" value="you@example.com" size="32" /&gt;
    &lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;Your Country:
        &lt;select name="country"&gt;
            &lt;option value="us" selected="selected"&gt;United States&lt;/option&gt;
            &lt;option value="il"&gt;Israel&lt;/option&gt;
            &lt;option value="de"&gt;Germany&lt;/option&gt;
        &lt;/select&gt;
    &lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;label&gt;Would you like to opt in?
        &lt;input type="hidden" name="opt_in" value="no" /&gt;
        &lt;input type="checkbox" name="opt_in" value="yes" checked="checked" /&gt;
    &lt;/label&gt;&lt;/p&gt;
&lt;/form&gt;
        </pre>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.action"></a>48.4.1.1. Action View Helper</h4></div></div></div>
<p>
        The <code class="code">Action</code> view helper enables view scripts to dispatch a
        given controller action; the result of the response object following the
        dispatch is then returned. These can be used when a particular action
        could generate re-usable content or "widget-ized" content.
    </p>
<p>
        Actions that result in a <code class="code">_forward()</code> or redirect are
        considered invalid, and will return an empty string.
    </p>
<p>
        The API for the <code class="code">Action</code> view helper follows that of most MVC
        components that invoke controller actions: <code class="code">action($action,
            $controller, $module = null, array $params = array())</code>.
        <code class="code">$action</code> and <code class="code">$controller</code> are required; if no
        module is specified, the default module is assumed.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.action.usage"></a><p class="title"><b>Example 48.1. Basic Usage of Action View Helper</b></p>
<div class="example-contents">
<p>
            As an example, you may have a <code class="code">CommentController</code> with a
            <code class="code">listAction()</code> method you wish to invoke in order to pull
            a list of comments for the current request:
        </p>
<pre class="programlisting">
&lt;div id="sidebar right"&gt; 
    &lt;div class="item"&gt;
        &lt;?= $this-&gt;action('list', 'comment', null, array('count' =&gt; 10)); ?&gt; 
    &lt;/div&gt;
&lt;/div&gt;
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.partial"></a>48.4.1.2. Partial Helper</h4></div></div></div>
<p>
        The <code class="code">Partial</code> view helper is used to render a specified
        template within its own variable scope. The primary use is for reusable
        template fragments with which you do not need to worry about variable
        name clashes. Additionally, they allow you to specify partial view
        scripts from specific modules.
    </p>
<p>
        A sibling to the <code class="code">Partial</code>, the <code class="code">PartialLoop</code> view
        helper allows you to pass iterable data, and render a partial for each
        item.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.partial.usage"></a><p class="title"><b>Example 48.2. Basic Usage of Partials</b></p>
<div class="example-contents">
<p>
            Basic usage of partials is to render a template fragment in its own
            view scope. Consider the following partial script:
        </p>
<pre class="programlisting">
&lt;?php // partial.phtml ?&gt;
&lt;ul&gt;
    &lt;li&gt;From: &lt;?= $this-&gt;escape($this-&gt;from) ?&gt;&lt;/li&gt;
    &lt;li&gt;Subject: &lt;?= $this-&gt;escape($this-&gt;subject) ?&gt;&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>
            You would then call it from your view script using the following:
        </p>
<pre class="programlisting">
&lt;?= $this-&gt;partial('partial.phtml', array(
    'from' =&gt; 'Team Framework', 
    'subject' =&gt; 'view partials')); ?&gt;
</pre>
<p>
            Which would then render:
        </p>
<pre class="programlisting">
&lt;ul&gt;
    &lt;li&gt;From: Team Framework&lt;/li&gt;
    &lt;li&gt;Subject: view partials&lt;/li&gt;
&lt;/ul&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="note"><table border="0" summary="Note: What is a model?">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">What is a model?</th>
</tr>
<tr><td align="left" valign="top">
<p>
                A model used with the <code class="code">Partial</code> view helper can be
                one of the following:
            </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                        <span class="emphasis"><em>Array</em></span>. If an array is passed, it
                        should be associative, as its key/value pairs are
                        assigned to the view with keys as view variables.
                </p></li>
<li><p>
                        <span class="emphasis"><em>Object implementing toArray()
                            method</em></span>. If an object is passed an has a
                        <code class="code">toArray()</code> method, the results of
                        <code class="code">toArray()</code> will be assigned to the view
                        object as view variables.
                </p></li>
<li><p>
                        <span class="emphasis"><em>Standard object</em></span>. Any other object
                        will assign the results of
                        <code class="code">object_get_vars()</code> (essentially all public
                        properties of the object) to the view object.
                </p></li>
</ul></div>
<p>
                If your model is an object, you may want to have it passed
                <span class="emphasis"><em>as an object</em></span> to the partial script, instead
                of serializing it to an array of variables. You can do this by
                setting the 'objectKey' property of the appropriate helper:
            </p>
<pre class="programlisting">
// Tell partial to pass objects as 'model' variable
$view-&gt;partial()-&gt;setObjectKey('model');

// Tell partial to pass objects from partialLoop as 'model' variable in final
// partial view script:
$view-&gt;partialLoop()-&gt;setObjectKey('model');
</pre>
<p>
                This technique is particularly useful when passing 
                <code class="code">Zend_Db_Table_Rowset</code>s to
                <code class="code">partialLoop()</code>, as you then have full access to your
                row objects within the view scripts, allowing you to call
                methods on them (such as retrieving values from parent or
                dependent rows).
            </p>
</td></tr>
</table></div>
<div class="example">
<a name="zend.view.helpers.initial.partial.partialloop"></a><p class="title"><b>Example 48.3. Using PartialLoop to Render Iterable Models</b></p>
<div class="example-contents">
<p>
            Typically, you'll want to use partials in a loop, to render the same
            content fragment many times; this way you can put large blocks of
            repeated content or complex display logic into a single location.
            However this has a performance impact, as the partial helper needs
            to be invoked once for each iteration.
        </p>
<p>
            The <code class="code">PartialLoop</code> view helper helps solve this issue. It
            allows you to pass an iterable item (array or object implementing
            <code class="code">Iterator</code>) as the model. It then iterates over this,
            passing, the items to the partial script as the model. Items in the
            iterator may be any model the <code class="code">Partial</code> view helper
            allows.
        </p>
<p>
            Let's assume the following partial view script:
        </p>
<pre class="programlisting">
&lt;? // partialLoop.phtml ?&gt;
    &lt;dt&gt;&lt;?= $this-&gt;key ?&gt;&lt;/dt&gt;
    &lt;dd&gt;&lt;?= $this-&gt;value ?&gt;&lt;/dd&gt;

</pre>
<p>
            And the following "model":
        </p>
<pre class="programlisting">&lt;?php
$model = array(
    array('key' =&gt; 'Mammal', 'value' =&gt; 'Camel'),
    array('key' =&gt; 'Bird', 'value' =&gt; 'Penguin'),
    array('key' =&gt; 'Reptile', 'value' =&gt; 'Asp'),
    array('key' =&gt; 'Fish', 'value' =&gt; 'Flounder'),
);
?&gt;</pre>
<p>
            In your view script, you could then invoke the
            <code class="code">PartialLoop</code> helper:
        </p>
<pre class="programlisting">
&lt;dl&gt;
&lt;?= $this-&gt;partialLoop('partialLoop.phtml', $model) ?&gt;
&lt;/dl&gt;
</pre>
<pre class="programlisting">
&lt;dl&gt;&lt;/dl&gt;
    &lt;dt&gt;Mammal&lt;/dt&gt;
    &lt;dd&gt;Camel&lt;/dd&gt;

    &lt;dt&gt;Bird&lt;/dt&gt;
    &lt;dd&gt;Penguin&lt;/dd&gt;

    &lt;dt&gt;Reptile&lt;/dt&gt;
    &lt;dd&gt;Asp&lt;/dd&gt;

    &lt;dt&gt;Fish&lt;/dt&gt;
    &lt;dd&gt;Flounder&lt;/dd&gt;

&lt;/dl&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.partial.modules"></a><p class="title"><b>Example 48.4. Rendering Partials in Other Modules</b></p>
<div class="example-contents">
<p>
            Sometime a partial will exist in a different module. If you know the
            name of the module, you can pass it as the second argument to either
            <code class="code">partial()</code> or <code class="code">partialLoop()</code>, moving the
            <code class="code">$model</code> argument to third position.
        </p>
<p>
            For instance, if there's a pager partial you wish to use that's in
            the 'list' module, you could grab it as follows:
        </p>
<pre class="programlisting">
&lt;?= $this-&gt;partial('pager.phtml', 'list', $pagerData) ?&gt;
</pre>
<p>
            In this way, you can re-use partials created specifically for other
            modules. That said, it's likely a better practice to put re-usable
            partials in shared view script paths.
        </p>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.placeholder"></a>48.4.1.3. Placeholder Helper</h4></div></div></div>
<p>
        The <code class="code">Placeholder</code> view helper is used to persist content
        between view scripts and view instances. It also offers some useful
        features such as aggregating content, capturing view script content
        for later use, and adding pre- and post-text to content (and custom
        separators for aggregated content).
    </p>
<div class="example">
<a name="zend.view.helpers.initial.placeholder.usage"></a><p class="title"><b>Example 48.5. Basic Usage of Placeholders</b></p>
<div class="example-contents">
<p>
            Basic usage of placeholders is to persist view data. Each invocation
            of the <code class="code">Placeholder</code> helper expects a placeholder name;
            the helper then returns a placeholder container object that you can
            either manipulate or simply echo out.
        </p>
<pre class="programlisting">
&lt;?php $this-&gt;placeholder('foo')-&gt;set("Some text for later") ?&gt;

&lt;?php 
    echo $this-&gt;placeholder('foo'); 
    // outputs "Some text for later"
?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.placeholder.aggregation"></a><p class="title"><b>Example 48.6. Using Placeholders to Aggregate Content</b></p>
<div class="example-contents">
<p>
            Aggregating content via placeholders can be useful at times as well.
            For instance, your view script may have a variable array from which
            you wish to retrieve messages to display later; a later view script
            can then determine how those will be rendered.
        </p>
<p>
            The <code class="code">Placeholder</code> view helper uses containers that extend
            <code class="code">ArrayObject</code>, providing a rich featureset for
            manipulating arrays. In addition, it offers a variety of methods for
            formatting the content stored in the container:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    <code class="code">setPrefix($prefix)</code> sets text with which to
                    prefix the content. Use <code class="code">getPrefix()</code> at any time
                    to determine what the current setting is.
            </p></li>
<li><p>
                    <code class="code">setPostfix($prefix)</code> sets text with which to
                    append the content. Use <code class="code">getPostfix()</code> at any time
                    to determine what the current setting is.
            </p></li>
<li><p>
                    <code class="code">setSeparator($prefix)</code> sets text with which to
                    separate aggregated content. Use <code class="code">getSeparator()</code>
                    at any time to determine what the current setting is.
            </p></li>
<li><p>
                    <code class="code">setIndent($prefix)</code> can be used to set an
                    indentation value for content. If an integer is passed,
                    that number of spaces will be used; if a string is passed,
                    the string will be used.  Use <code class="code">getIndent()</code>
                    at any time to determine what the current setting is.
            </p></li>
</ul></div>
<pre class="programlisting">
&lt;!-- first view script --&gt;
&lt;?php $this-&gt;placeholder('foo')-&gt;exchangeArray($this-&gt;data) ?&gt;
</pre>
<pre class="programlisting">
&lt;!-- later view script --&gt;
&lt;?php 
$this-&gt;placeholder('foo')-&gt;setPrefix("&lt;ul&gt;\n    &lt;li&gt;")
                         -&gt;setSeparator("&lt;/li&gt;&lt;li&gt;\n") 
                         -&gt;setIndent(4)
                         -&gt;setPostfix("&lt;/li&gt;&lt;/ul&gt;\n");
?&gt;

&lt;?php 
    echo $this-&gt;placeholder('foo'); 
    // outputs as unordered list with pretty indentation
?&gt;
</pre>
<p>
            Because the <code class="code">Placeholder</code> container objects extend
            <code class="code">ArrayObject</code>, you can also assign content to a specific
            key in the container easily, instead of simply pushing it into the
            container. Keys may be accessed either as object properties or as
            array keys.
        </p>
<pre class="programlisting">
&lt;?php $this-&gt;placeholder('foo')-&gt;bar = $this-&gt;data ?&gt;
&lt;?php echo $this-&gt;placeholder('foo')-&gt;bar ?&gt;

&lt;?php
$foo = $this-&gt;placeholder('foo');
echo $foo['bar'];
?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.placeholder.capture"></a><p class="title"><b>Example 48.7. Using Placeholders to Capture Content</b></p>
<div class="example-contents">
<p>
            Occasionally you may have content for a placeholder in a view script
            that is easiest to template; the <code class="code">Placeholder</code> view
            helper allows you to capture arbitrary content for later rendering
            using the following API.
        </p>
<div class="itemizedlist"><ul type="disc">
<li>
<p>
                    <code class="code">captureStart($type, $key)</code> begins capturing
                    content. 
                </p>
<p>
                    <code class="code">$type</code> should be one of the
                    <code class="code">Placeholder</code> constants <code class="code">APPEND</code> or
                    <code class="code">SET</code>. If <code class="code">APPEND</code>, captured content
                    is appended to the list of current content in the
                    placeholder; if <code class="code">SET</code>, captured content is used
                    as the sole value of the placeholder (potentially replacing
                    any previous content). By default, <code class="code">$type</code> is
                    <code class="code">APPEND</code>.
                </p>
<p>
                    <code class="code">$key</code> can be used to specify a specific key in
                    the placeholder container to which you want content
                    captured.
                </p>
<p>
                    <code class="code">captureStart()</code> locks capturing until
                    <code class="code">captureEnd()</code> is called; you cannot nest
                    capturing with the same placholder container. Doing so will
                    raise an exception.
                </p>
</li>
<li><p>
                    <code class="code">captureEnd()</code> stops capturing content, and
                    places it in the container object according to how
                    <code class="code">captureStart()</code> was called.
            </p></li>
</ul></div>
<pre class="programlisting">
&lt;!-- Default capture: append --&gt;
&lt;?php $this-&gt;placeholder('foo')-&gt;captureStart(); 
foreach ($this-&gt;data as $datum): ?&gt;
&lt;div class="foo"&gt;
    &lt;h2&gt;&lt;?= $datum-&gt;title ?&gt;&lt;/h2&gt;
    &lt;p&gt;&lt;?= $datum-&gt;content ?&gt;&lt;/p&gt;
&lt;/div&gt;
&lt;?php endforeach; ?&gt;
&lt;?php $this-&gt;placeholder('foo')-&gt;captureEnd() ?&gt;

&lt;?php echo $this-&gt;placeholder('foo') ?&gt;
</pre>
<pre class="programlisting">
&lt;!-- Capture to key --&gt;
&lt;?php $this-&gt;placeholder('foo')-&gt;captureStart('SET', 'data'); 
foreach ($this-&gt;data as $datum): ?&gt;
&lt;div class="foo"&gt;
    &lt;h2&gt;&lt;?= $datum-&gt;title ?&gt;&lt;/h2&gt;
    &lt;p&gt;&lt;?= $datum-&gt;content ?&gt;&lt;/p&gt;
&lt;/div&gt;
 &lt;?php endforeach; ?&gt;
&lt;?php $this-&gt;placeholder('foo')-&gt;captureEnd() ?&gt;

&lt;?php echo $this-&gt;placeholder('foo')-&gt;data ?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="sect4" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="zend.view.helpers.initial.placeholder.implementations"></a>48.4.1.3.1. Concrete Placeholder Implementations</h5></div></div></div>
<p>
            Zend Framework ships with a number of "concrete" placeholder
            implementations. These are for commonly used placeholders: doctype,
            page title, and various &lt;head&gt; elements. In all cases, calling
            the placeholder with no arguments returns the element itself. 
        </p>
<p>
            Documentation for each element is covered separately, as linked
            below:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.doctype" title="48.4.1.4. Doctype Helper">Doctype</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.headlink" title="48.4.1.5. HeadLink Helper">HeadLink</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.headmeta" title="48.4.1.6. HeadMeta Helper">HeadMeta</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.headscript" title="48.4.1.7. HeadScript Helper">HeadScript</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.headstyle" title="48.4.1.8. HeadStyle Helper">HeadStyle</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.headtitle" title="48.4.1.9. HeadTitle Helper">HeadTitle</a>
            </p></li>
<li><p>
                    <a href="zend.view.helpers.html#zend.view.helpers.initial.inlinescript" title="48.4.1.11. InlineScript Helper">InlineScript</a>
            </p></li>
</ul></div>
</div>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.doctype"></a>48.4.1.4. Doctype Helper</h4></div></div></div>
<p>
        Valid HTML and XHTML documents should include a <code class="code">DOCTYPE</code>
        declaration. Besides being difficult to remember, these can also affect
        how certain elements in your document should be rendered (for instance,
        CDATA escaping in <code class="code">&lt;script&gt;</code> and
        <code class="code">&lt;style&gt;</code> elements.
    </p>
<p>
        The <code class="code">Doctype</code> helper allows you to specify one of the
        following types:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">XHTML11</code></p></li>
<li><p><code class="code">XHTML1_STRICT</code></p></li>
<li><p><code class="code">XHTML1_TRANSITIONAL</code></p></li>
<li><p><code class="code">XHTML1_FRAMESET</code></p></li>
<li><p><code class="code">XHTML_BASIC1</code></p></li>
<li><p><code class="code">HTML4_STRICT</code></p></li>
<li><p><code class="code">HTML4_LOOSE</code></p></li>
<li><p><code class="code">HTML4_FRAMESET</code></p></li>
</ul></div>
<p>
        You can also specify a custom doctype as long as it is well-formed.
    </p>
<p>
        The <code class="code">Doctype</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.doctype.basicusage"></a><p class="title"><b>Example 48.8. Doctype Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify the doctype at any time. However, helpers that 
            depend on the doctype for their output will recognize it only after 
            you have set it, so the easyest approach is to specify it in your 
            bootstrap:
        </p>
<pre class="programlisting">
$doctypeHelper = new Zend_View_Helper_Doctype();
$doctypeHelper-&gt;doctype('XHTML1_STRICT');
</pre>
<p>
            And then print it out on top of your layout script:
        </p>
<pre class="programlisting">
&lt;?php echo $this-&gt;doctype() ?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.doctype.retrieving"></a><p class="title"><b>Example 48.9. Retrieving the Doctype</b></p>
<div class="example-contents">
<p>
            If you need to know the doctype, you can do so by calling
            <code class="code">getDoctype()</code> on the object, which is returned by
            invoking the helper.
        </p>
<pre class="programlisting">&lt;?php
$doctype = $view-&gt;doctype()-&gt;getDoctype();
?&gt;</pre>
<p>
            Typically, you'll simply want to know if the doctype is XHTML or
            not; for this, the <code class="code">isXhtml()</code> method will suffice:
        </p>
<pre class="programlisting">&lt;?php
if ($view-&gt;doctype()-&gt;isXhtml()) {
    // do something differently
}
?&gt;</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.headlink"></a>48.4.1.5. HeadLink Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;link&gt;</code> element is increasingly used for
        linking a variety of resources for your site: stylesheets, feeds,
        favicons, trackbacks, and more. The <code class="code">HeadLink</code> helper
        provides a simple interface for creating and aggregating these elements
        for later retrieval and output in your layout script.
    </p>
<p>
        The <code class="code">HeadLink</code> helper has special methods for adding
        stylesheet links to its stack:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">appendStylesheet($href, $media,
                    $conditionalStylesheet)</code></p></li>
<li><p><code class="code">offsetSetStylesheet($index, $href, $media,
                    $conditionalStylesheet)</code></p></li>
<li><p><code class="code">prependStylesheet($href, $media,
                    $conditionalStylesheet)</code></p></li>
<li><p><code class="code">setStylesheet($href, $media,
                    $conditionalStylesheet)</code></p></li>
</ul></div>
<p>
        The <code class="code">$media</code> value defaults to 'screen', but may be any valid
        media value. <code class="code">$conditionalStylesheet</code> is a boolean, and will
        be used at rendering time to determine if special comments should be
        included to prevent loading of the stylesheet on certain platforms.
    </p>
<p>
        Additionally, the <code class="code">HeadLink</code> helper has special methods for
        adding 'alternate' links to its stack:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">appendAlternate($href, $type,
                    $title)</code></p></li>
<li><p><code class="code">offsetSetAlternate($index, $href, $type,
                    $title)</code></p></li>
<li><p><code class="code">prependAlternate($href, $type,
                    $title)</code></p></li>
<li><p><code class="code">setAlternate($href, $type,
                    $title)</code></p></li>
</ul></div>
<p>
        The <code class="code">headLink()</code> helper method allows specifying all
        attributes necessary for a <code class="code">&lt;link&gt;</code> element, and allows
        you to also specify placement -- whether the new element replaces all
        others, prepends (top of stack), or appends (end of stack).
    </p>
<p>
        The <code class="code">HeadLink</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.headlink.basicusage"></a><p class="title"><b>Example 48.10. HeadLink Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify a <code class="code">headLink</code> at any time. Typically, you
            will specify global links in your layout script, and application
            specific links in your application view scripts. In your layout
            script, in the &lt;head&gt; section, you will then echo the helper
            to output it.
        </p>
<pre class="programlisting">
&lt;?php // setting links in a view script:
$this-&gt;headLink()-&gt;appendStylesheet('/styles/basic.css')
                 -&gt;headLink(array('rel' =&gt; 'favicon', 'href' =&gt; '/img/favicon.ico'), 'PREPEND')
                 -&gt;prependStylesheet('/styles/moz.css', 'screen', true);
?&gt;
&lt;?php // rendering the links: ?&gt;
&lt;?= $this-&gt;headLink() ?&gt;
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.headmeta"></a>48.4.1.6. HeadMeta Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;meta&gt;</code> element is used to provide meta
        information about your HTML document -- typically keywords, document
        character set, caching pragmas, etc. Meta tags may be either of the
        'http-equiv' or 'name' types, must contain a 'content' attribute, and
        can also have either of the 'lang' or 'scheme' modifier attributes.
    </p>
<p>
        The <code class="code">HeadMeta</code> helper supports the following methods for
        setting and adding meta tags:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">appendName($keyValue, $content,
                    $conditionalName)</code></p></li>
<li><p><code class="code">offsetSetName($index, $keyValue, $content,
                    $conditionalName)</code></p></li>
<li><p><code class="code">prependName($keyValue, $content,
                    $conditionalName)</code></p></li>
<li><p><code class="code">setName($keyValue, $content,
                    $modifiers)</code></p></li>
<li><p><code class="code">appendHttpEquiv($keyValue, $content,
                    $conditionalHttpEquiv)</code></p></li>
<li><p><code class="code">offsetSetHttpEquiv($index, $keyValue, $content,
                    $conditionalHttpEquiv)</code></p></li>
<li><p><code class="code">prependHttpEquiv($keyValue, $content,
                    $conditionalHttpEquiv)</code></p></li>
<li><p><code class="code">setHttpEquiv($keyValue, $content,
                    $modifiers)</code></p></li>
</ul></div>
<p>
        The <code class="code">$keyValue</code> item is used to define a value for the 'name'
        or 'http-equiv' key; <code class="code">$content</code> is the value for the
        'content' key, and <code class="code">$modifiers</code> is an optional associative
        array that can contain keys for 'lang' and/or 'scheme'.
    </p>
<p>
        You may also set meta tags using the <code class="code">headMeta()</code> helper
        method, which has the following signature: <code class="code">headMeta($content,
            $keyValue, $keyType = 'name', $modifiers = array(), $placement =
            'APPEND')</code>. <code class="code">$keyValue</code> is the content for the key
        specified in <code class="code">$keyType</code>, which should be either 'name' or
        'http-equiv'. <code class="code">$placement</code> can be either 'SET' (overwrites
        all previously stored values), 'APPEND' (added to end of stack), or
        'PREPEND' (added to top of stack).
    </p>
<p>
        <code class="code">HeadMeta</code> overrides each of <code class="code">append()</code>,
        <code class="code">offsetSet()</code>, <code class="code">prepend()</code>, and <code class="code">set()</code>
        to enforce usage of the special methods as listed above. Internally, it
        stores each item as a <code class="code">stdClass</code> token, which it later
        serializes using the <code class="code">itemToString()</code> method. This allows you
        to perform checks on the items in the stack, and optionally modify these
        items by simply modifying the object returned.
    </p>
<p>
        The <code class="code">HeadMeta</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.headmeta.basicusage"></a><p class="title"><b>Example 48.11. HeadMeta Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify a new meta tag at any time. Typically, you
            will specify client-side caching rules or SEO keywords.
        </p>
<p>
            For instance, if you wish to specify SEO keywords, you'd be creating
            a meta name tag with the name 'keywords' and the content the
            keywords you wish to associate with your page:
        </p>
<pre class="programlisting">
&lt;?php // setting meta keywords
$this-&gt;headMeta()-&gt;appendName('keywords', 'framework php productivity');
?&gt;
</pre>
<p>
            If you wishedto set some client-side caching rules, you'd set
            http-equiv tags with the rules you wish to enforce:
        </p>
<pre class="programlisting">
&lt;?php // disabling client-side cache
$this-&gt;headMeta()-&gt;appendHttpEquiv('expires', 'Wed, 26 Feb 1997 08:21:57 GMT')
                 -&gt;appendHttpEquiv('pragma', 'no-cache')
                 -&gt;appendHttpEquiv('Cache-Control', 'no-cache');
?&gt;
</pre>
<p>
            Another popular use for meta tags is setting the content type,
            character set, and language:
        </p>
<pre class="programlisting">
&lt;?php // setting content type and character set
$this-&gt;headMeta()-&gt;appendHttpEquiv('Content-Type', 'text/html; charset=UTF-8')
                 -&gt;appendHttpEquiv('Content-Language', 'en-US');
?&gt;
</pre>
<p>
            As a final example, an easy way to display a transitional message
            before a redirect is using a "meta refresh":
        </p>
<pre class="programlisting">
&lt;?php // setting a meta refresh for 3 seconds to a new url:
$this-&gt;headMeta()-&gt;appendHttpEquiv('Refresh', '3;URL=http://www.some.org/some.html');
?&gt;
</pre>
<p>
            When you're ready to place your meta tags in the layout, simply echo
            the helper:
        </p>
<pre class="programlisting">
&lt;?= $this-&gt;headMeta() ?&gt;
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.headscript"></a>48.4.1.7. HeadScript Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;script&gt;</code> element is used to either provide
        inline client-side scripting elements or link to a remote resource
        containing client-side scripting code. The <code class="code">HeadScript</code>
        helper allows you to manage both.
    </p>
<p>
        The <code class="code">HeadScript</code> helper supports the following methods for
        setting and adding scripts:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">appendFile($src, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">offsetSetFile($index, $src, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">prependFile($src, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">setFile($src, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">appendScript($script, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">offsetSetScript($index, $script, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">prependScript($script, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
<li><p><code class="code">setScript($script, $type = 'text/javascript',
                    $attrs = array())</code></p></li>
</ul></div>
<p>
        In the case of the <code class="code">*File()</code> methods, <code class="code">$src</code> is
        the remote location of the script to load; this is usually in the form
        of a URL or a path. For the <code class="code">*Script()</code> methods,
        <code class="code">$script</code> is the client-side scripting directives you wish to
        use in the element.
    </p>
<p>
        <code class="code">HeadScript</code> also allows capturing scripts; this can be
        useful if you want to create the client-side script programmatically,
        and then place it elsewhere. The usage for this will be showed in an
        example below.
    </p>
<p>
        Finally, you can also use the <code class="code">headScript()</code> method to
        quickly add script elements; the signature for this is
        <code class="code">headScript($mode = 'FILE', $spec, $placement = 'APPEND')</code>.
        The <code class="code">$mode</code> is either 'FILE' or 'SCRIPT', depending on if
        you're linking a script or defining one. <code class="code">$spec</code> is either
        the script file to link or the script source itself.
        <code class="code">$placement</code> should be either 'APPEND', 'PREPEND', or 'SET'.
    </p>
<p>
        <code class="code">HeadScript</code> overrides each of <code class="code">append()</code>,
        <code class="code">offsetSet()</code>, <code class="code">prepend()</code>, and <code class="code">set()</code>
        to enforce usage of the special methods as listed above. Internally, it
        stores each item as a <code class="code">stdClass</code> token, which it later
        serializes using the <code class="code">itemToString()</code> method. This allows you
        to perform checks on the items in the stack, and optionally modify these
        items by simply modifying the object returned.
    </p>
<p>
        The <code class="code">HeadScript</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>.
    </p>
<div class="note"><table border="0" summary="Note: Use InlineScript for HTML Body Scripts">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Use InlineScript for HTML Body Scripts</th>
</tr>
<tr><td align="left" valign="top"><p>
            <code class="code">HeadScript</code>'s sibling helper, <a href="zend.view.helpers.html#zend.view.helpers.initial.inlinescript" title="48.4.1.11. InlineScript Helper">InlineScript</a>, 
            should be used when you wish to include scripts inline in the HTML
            <code class="code">body</code>. Placing scripts at the end of your document is a
            good practice for speeding up delivery of your page, particularly
            when using 3rd party analytics scripts.
        </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note: Arbitrary Attributes are Disabled by Default">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Arbitrary Attributes are Disabled by Default</th>
</tr>
<tr><td align="left" valign="top">
<p>
            By default, <code class="code">HeadScript</code> only will render
            <code class="code">&lt;script&gt;</code> attributes that are blessed by the W3C.
            These include 'type', 'charset', 'defer', 'language', and 'src'.
            However, some javascript frameworks, notably <a href="http://www.dojotoolkit.org/" target="_top">Dojo</a>, utilize custom
            attributes in order to modify behavior. To allow such attributes,
            you can enable them via the
            <code class="code">setAllowArbitraryAttributes()</code> method:
        </p>
<pre class="programlisting">&lt;?php
$this-&gt;headScript()-&gt;setAllowArbitraryAttributes(true);
?&gt;</pre>
</td></tr>
</table></div>
<div class="example">
<a name="zend.view.helpers.initial.headscript.basicusage"></a><p class="title"><b>Example 48.12. HeadScript Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify a new script tag at any time. As noted above, these
            may be links to outside resource files or scripts themselves.
        </p>
<pre class="programlisting">
&lt;?php // adding scripts
$this-&gt;headScript()-&gt;appendFile('/js/prototype.js')
                   -&gt;appendScript($onloadScript);
?&gt;
</pre>
<p>
            Order is often important with client-side scripting; you may need to
            ensure that libraries are loaded in a specific order due to
            dependencies each have; use the various append, prepend, and
            offsetSet directives to aid in this task:
        </p>
<pre class="programlisting">
&lt;?php // Putting scripts in order

// place at a particular offset to ensure loaded last
$this-&gt;headScript()-&gt;offsetSetScript(100, '/js/myfuncs.js');

// use scriptaculous effects (append uses next index, 101)
$this-&gt;headScript()-&gt;appendScript('/js/scriptaculous.js');

// but always have base prototype script load first:
$this-&gt;headScript()-&gt;prependScript('/js/prototype.js');
?&gt;
</pre>
<p>
            When you're finally ready to output all scripts in your layout
            script, simply echo the helper:
        </p>
<pre class="programlisting">
&lt;?= $this-&gt;headScript() ?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.headscript.capture"></a><p class="title"><b>Example 48.13. Capturing Scripts Using the HeadScript Helper</b></p>
<div class="example-contents">
<p>
            Sometimes you need to generate client-side scripts programmatically.
            While you could use string concatenation, heredocs, and the like,
            often it's easier just to do so by creating the script and
            sprinkling in PHP tags. <code class="code">HeadScript</code> lets you do just
            that, capturing it to the stack:
        </p>
<pre class="programlisting">
&lt;?php $this-&gt;headScript()-&gt;captureStart() ?&gt;
var action = '&lt;?= $this-&gt;baseUrl ?&gt;';
$('foo_form').action = action;
&lt;?php $this-&gt;headScript()-&gt;captureEnd() ?&gt;
</pre>
<p>
            The following assumptions are made:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    The script will be appended to the stack. If you wish for it
                    to replace the stack or be added to the top, you will need
                    to pass 'SET' or 'PREPEND', respectively, as the first
                    argument to <code class="code">captureStart()</code>.
            </p></li>
<li><p>
                    The script MIME type is assumed to be 'text/javascript'; if you
                    wish to specify a different type, you will need to pass it
                    as the second argument to <code class="code">captureStart()</code>.
            </p></li>
<li><p>
                    If you wish to specify any additional attributes for the
                    <code class="code">&lt;script&gt;</code> tag, pass them in an array as
                    the third argument to <code class="code">captureStart()</code>.
            </p></li>
</ul></div>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.headstyle"></a>48.4.1.8. HeadStyle Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;style&gt;</code> element is used to include
        CSS stylesheets inline in the HTML <code class="code">&lt;head&gt;</code> element. 
    </p>
<div class="note"><table border="0" summary="Note: Use HeadLink to link CSS files">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Use HeadLink to link CSS files</th>
</tr>
<tr><td align="left" valign="top"><p>
            <a href="zend.view.helpers.html#zend.view.helpers.initial.headlink" title="48.4.1.5. HeadLink Helper">HeadLink</a>
            should be used to create <code class="code">&lt;link&gt;</code> elements for
            including external stylesheets. <code class="code">HeadScript</code> is used when
            you wish to define your stylesheets inline.
        </p></td></tr>
</table></div>
<p>
        The <code class="code">HeadStyle</code> helper supports the following methods for
        setting and adding stylesheet declarations:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="code">appendStyle($content, $attributes =
                    array())</code></p></li>
<li><p><code class="code">offsetSetStyle($index, $content, $attributes =
                    array())</code></p></li>
<li><p><code class="code">prependStyle($content, $attributes =
                    array())</code></p></li>
<li><p><code class="code">setStyle($content, $attributes =
                    array())</code></p></li>
</ul></div>
<p>
        In all cases, <code class="code">$content</code> is the actual CSS declarations.
        <code class="code">$attributes</code> are any additional attributes you wish to provide to the
        <code class="code">style</code> tag: lang, title, media, or dir are all permissable.
    </p>
<p>
        <code class="code">HeadStyle</code> also allows capturing style declarations; this
        can be useful if you want to create the declarations programmatically,
        and then place them elsewhere. The usage for this will be showed in an
        example below.
    </p>
<p>
        Finally, you can also use the <code class="code">headStyle()</code> method to
        quickly add declarations elements; the signature for this is
        <code class="code">headStyle($content$placement = 'APPEND', $attributes = array())</code>.
        <code class="code">$placement</code> should be either 'APPEND', 'PREPEND', or 'SET'.
    </p>
<p>
        <code class="code">HeadStyle</code> overrides each of <code class="code">append()</code>,
        <code class="code">offsetSet()</code>, <code class="code">prepend()</code>, and <code class="code">set()</code>
        to enforce usage of the special methods as listed above. Internally, it
        stores each item as a <code class="code">stdClass</code> token, which it later
        serializes using the <code class="code">itemToString()</code> method. This allows you
        to perform checks on the items in the stack, and optionally modify these
        items by simply modifying the object returned.
    </p>
<p>
        The <code class="code">HeadStyle</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.headstyle.basicusage"></a><p class="title"><b>Example 48.14. HeadStyle Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify a new style tag at any time:
        </p>
<pre class="programlisting">
&lt;?php // adding styles
$this-&gt;headStyle()-&gt;appendStyle($styles);
?&gt;
</pre>
<p>
            Order is very important with CSS; you may need to ensure that
            declarations are loaded in a specific order due to the order of the
            cascade; use the various append, prepend, and offsetSet directives
            to aid in this task:
        </p>
<pre class="programlisting">
&lt;?php // Putting styles in order

// place at a particular offset:
$this-&gt;headStyle()-&gt;offsetSetStyle(100, $customStyles);

// place at end:
$this-&gt;headStyle()-&gt;appendStyle($finalStyles);

// place at beginning
$this-&gt;headStyle()-&gt;prependStyle($firstStyles);
?&gt;
</pre>
<p>
            When you're finally ready to output all style declarations in your
            layout script, simply echo the helper:
        </p>
<pre class="programlisting">
&lt;?= $this-&gt;headStyle() ?&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.headstyle.capture"></a><p class="title"><b>Example 48.15. Capturing Style Declarations Using the HeadStyle Helper</b></p>
<div class="example-contents">
<p>
            Sometimes you need to generate CSS style declarations
            programmatically.  While you could use string concatenation,
            heredocs, and the like, often it's easier just to do so by creating
            the styles and sprinkling in PHP tags. <code class="code">HeadStyle</code> lets
            you do just that, capturing it to the stack:
        </p>
<pre class="programlisting">
&lt;?php $this-&gt;headStyle()-&gt;captureStart() ?&gt;
body {
    background-color: &lt;?= $this-&gt;bgColor ?&gt;;
}
&lt;?php $this-&gt;headStyle()-&gt;captureEnd() ?&gt;
</pre>
<p>
            The following assumptions are made:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    The style declarations will be appended to the stack. If you
                    wish for them to replace the stack or be added to the top,
                    you will need to pass 'SET' or 'PREPEND', respectively, as
                    the first argument to <code class="code">captureStart()</code>.
            </p></li>
<li><p>
                    If you wish to specify any additional attributes for the
                    <code class="code">&lt;style&gt;</code> tag, pass them in an array as
                    the second argument to <code class="code">captureStart()</code>.
            </p></li>
</ul></div>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.headtitle"></a>48.4.1.9. HeadTitle Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;title&gt;</code> element is used to provide a title
        for an HTML document. The <code class="code">HeadTitle</code> helper allows you to
        programmatically create and store the title for later retrieval and
        output.
    </p>
<p>
        The <code class="code">HeadTitle</code> helper is a concrete implementation of the 
        <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" title="48.4.1.3. Placeholder Helper">Placeholder
            helper</a>. It overrides the <code class="code">toString()</code> method to
        enforce generating a <code class="code">&lt;title&gt;</code> element, and adds a
        <code class="code">headTitle()</code> method for quick and easy setting and
        aggregation of title elements. The signature for that method is
        <code class="code">headTitle($title, $setType = 'APPEND')</code>; by default, the
        value is appended to the stack (aggregating title segments), but you may
        also specify either 'PREPEND' (place at top of stack) or 'SET'
        (overwrite stack).
    </p>
<div class="example">
<a name="zend.view.helpers.initial.headtitle.basicusage"></a><p class="title"><b>Example 48.16. HeadTitle Helper Basic Usage</b></p>
<div class="example-contents">
<p>
            You may specify a title tag at any time. A typical usage would have
            you setting title segments for each level of depth in your
            application: site, controller, action, and potentially resource.
        </p>
<pre class="programlisting">&lt;?php 
// setting the controller and action name as title segments:
$request = Zend_Controller_Front::getInstance()-&gt;getRequest();
$this-&gt;headTitle($request-&gt;getActionName())
     -&gt;headTitle($request-&gt;getControllerName());

// setting the site in the title; possibly in the layout script:
$this-&gt;headTitle('Zend Framework');

// setting a separator string for segments:
$this-&gt;headTitle()-&gt;setSeparator(' / ');
?&gt;
</pre>
<p>
            When you're finally ready to render the title in your layout
            script, simply echo the helper:
        </p>
<pre class="programlisting">
&lt;!-- renders &lt;action&gt; / &lt;controller&gt; / Zend Framework --&gt;
&lt;?= $this-&gt;headTitle() ?&gt;
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.object"></a>48.4.1.10. HTML Object Helpers</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;object&gt;</code> element is used for embedding
        media like Flash or QuickTime in web pages. The object view helpers take
        care of embedding media with minimum effort.
    </p>
<p>
        There are four initial Object helpers:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                <code class="code">formFlash</code>
                Generates markup for embedding Flash files. 
            </p></li>
<li><p>
                <code class="code">formObject</code>
                Generates markup for embedding a custom Object.
            </p></li>
<li><p>
                <code class="code">formPage</code>
                Generates markup for embedding other (X)HTML pages.
            </p></li>
<li><p>
                <code class="code">formQuicktime</code>
                Generates markup for embedding QuickTime files.
            </p></li>
</ul></div>
<p>
        All of these helpers share a similar interface. For this reason, this
        documentation will only contain examples of two of these helpers.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.object.flash"></a><p class="title"><b>Example 48.17. Flash helper</b></p>
<div class="example-contents">
<p>
            Embedding Flash in your page using the helper is pretty straight-forward.
            The only required argument is the resource URI.
        </p>
<pre class="programlisting">&lt;?php echo $this-&gt;htmlFlash('/path/to/flash.swf'); ?&gt;</pre>
<p>
            This outputs the following HTML:
        </p>
<pre class="programlisting">
&lt;object data="/path/to/flash.swf" type="application/x-shockwave-flash" 
    classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" 
    codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab"&gt;
&lt;/object&gt;
</pre>
</div>
</div>
<br class="example-break"><p>
        Additionally you can specify attributes, parameters and content that can
        be rendered along with the <code class="code">&lt;object&gt;</code>. This will
        be demonstrated using the <code class="code">htmlObject</code> helper.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.object.object"></a><p class="title"><b>Example 48.18. Customizing the object by passing additional arguments</b></p>
<div class="example-contents">
<p>
            The first argument in the object helpers is always required. It is
            the URI to the resource you want to embed. The second argument is
            only required in the <code class="code">htmlObject</code> helper. The other helpers
            already contain the correct value for this argument. The third
            argument is used for passing along attributes to the object element.
            It only accepts an array with key-value pairs. The <code class="code">classid</code>
            and <code class="code">codebase</code> are examples of such attributes. The fourth
            argument also only takes a key-value array and uses them to create
            <code class="code">&lt;param&gt;</code> elements. You will see an example
            of this shortly. Lastly, there is the option of providing additional
            content to the object. Now for an example which utilizes all arguments.
        </p>
<pre class="programlisting">
echo $this-&gt;htmlObject(
    '/path/to/file.ext', 
    'mime/type', 
    array(
        'attr1' =&gt; 'aval1', 
        'attr2' =&gt; 'aval2'
    ), 
    array(
        'param1' =&gt; 'pval1', 
        'param2' =&gt; 'pval2'
    ), 
    'some content'
);

/*
This would output:

&lt;object data="/path/to/file.ext" type="mime/type" 
    attr1="aval1" attr2="aval2"&gt;
    &lt;param name="param1" value="pval1" /&gt;
    &lt;param name="param2" value="pval2" /&gt;
    some content
&lt;/object&gt;
*/
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.inlinescript"></a>48.4.1.11. InlineScript Helper</h4></div></div></div>
<p>
        The HTML <code class="code">&lt;script&gt;</code> element is used to either provide
        inline client-side scripting elements or link to a remote resource
        containing client-side scripting code. The <code class="code">InlineScript</code>
        helper allows you to manage both. It is derived from <a href="zend.view.helpers.html#zend.view.helpers.initial.headscript" title="48.4.1.7. HeadScript Helper">HeadScript</a>,
        and any method of that helper is available; however, use the
        <code class="code">inlineScript()</code> method in place of
        <code class="code">headScript()</code>.
    </p>
<div class="note"><table border="0" summary="Note: Use InlineScript for HTML Body Scripts">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Use InlineScript for HTML Body Scripts</th>
</tr>
<tr><td align="left" valign="top">
<p>
            <code class="code">InlineScript</code>, should be used when you wish to include
            scripts inline in the HTML <code class="code">body</code>. Placing scripts at the
            end of your document is a good practice for speeding up delivery of
            your page, particularly when using 3rd party analytics scripts.
        </p>
<p>
            Some JS libraries need to be included in the HTML <code class="code">head</code>;
            use <a href="zend.view.helpers.html#zend.view.helpers.initial.headscript" title="48.4.1.7. HeadScript Helper">HeadScript</a>
            for those scripts.
        </p>
</td></tr>
</table></div>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.json"></a>48.4.1.12. JSON Helper</h4></div></div></div>
<p>
        When creating views that return JSON, it's important to also set the
        appropriate response header. The JSON view helper does exactly that. In
        addition, by default, it disables layouts (if currently enabled), as
        layouts generally aren't used with JSON responses.
    </p>
<p>
        The JSON helper sets the following header:
    </p>
<pre class="programlisting">
Content-Type: application/json
</pre>
<p>
        Most AJAX libraries look for this header when parsing responses to
        determine how to handle the content.
    </p>
<p>
        Usage of the JSON helper is very straightforward:
    </p>
<pre class="programlisting">&lt;?php
&lt;?= $this-&gt;json($this-&gt;data) ?&gt;
?&gt;</pre>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="zend.view.helpers.initial.translate"></a>48.4.1.13. Translate Helper</h4></div></div></div>
<p>
        Often web sites are available in several languages. To translate the
        content of a site you should simply use <a href="zend.translate.html#zend.translate.introduction" title="44.1. Introduction">Zend Translate</a> and to
        integrate <code class="code">Zend Translate</code> within your view you should use
        the <code class="code">Translate</code> View Helper.
    </p>
<p>
        In all following examples we are using the simple Array Translation
        Adapter. Of course you can also use any instance of
        <code class="code">Zend_Translate</code> and also any subclasses of
        <code class="code">Zend_Translate_Adapter</code>. There are several ways to initiate
        the <code class="code">Translate</code> View Helper:
    </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                Registered, through a previously registered instance in
                <code class="code">Zend_Registry</code>
            </p></li>
<li><p>
                Afterwards, through the fluent interface
            </p></li>
<li><p>
                Directly, through initiating the class
            </p></li>
</ul></div>
<p>
        A registered instance of <code class="code">Zend_Translate</code> is the preferred
        usage for this helper.  You can also select the locale to be used simply
        before you add the adapter to the registry.
    </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            We are speaking of locales instead of languages because a language
            also may contain a region.  For example English is spoken in
            different dialects. There may be a translation for British and one
            for American English. Therefore, we say "locale" instead of
            "language."
        </p></td></tr>
</table></div>
<div class="example">
<a name="zend.view.helpers.initial.translate.registered"></a><p class="title"><b>Example 48.19. Registered instance</b></p>
<div class="example-contents">
<p>
            To use a registered instance just create an instance of
            <code class="code">Zend_Translate</code> or <code class="code">Zend_Translate_Adapter</code>
            and register it within <code class="code">Zend_Registry</code> using
            <code class="code">Zend_Translate</code> as its key.
        </p>
<pre class="programlisting">&lt;?php
// our example adapter
$adapter = new Zend_Translate('array', array('simple' =&gt; 'einfach'), 'de');
Zend_Registry::set('Zend_Translate', $adapter);

// within your view
echo $this-&gt;translate('simple');
// this returns 'einfach'
?&gt;</pre>
</div>
</div>
<br class="example-break"><p>
        If you are more familiar with the fluent interface, then you can also
        create an instace within your view and initiate the helper afterwards.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.afterwards"></a><p class="title"><b>Example 48.20. Within the view</b></p>
<div class="example-contents">
<p>
            To use the fluent interface, create an instance of
            <code class="code">Zend_Translate</code> or <code class="code">Zend_Translate_Adapter</code>,
            call the helper without a parameter, and call the
            <code class="code">setTranslator()</code> method.
        </p>
<pre class="programlisting">&lt;?php
// within your view
$adapter = new Zend_Translate('array', array('simple' =&gt; 'einfach'), 'de');
$this-&gt;translate()-&gt;setTranslator($adapter)-&gt;translate('simple');
// this returns 'einfach'
?&gt;</pre>
</div>
</div>
<br class="example-break"><p>
        If you are using the helper without <code class="code">Zend_View</code> then you can
        also use it directly.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.directly"></a><p class="title"><b>Example 48.21. Direct usage</b></p>
<div class="example-contents">
<pre class="programlisting">&lt;?php
// our example adapter
$adapter = new Zend_Translate('array', array('simple' =&gt; 'einfach'), 'de');

// initiate the adapter
$translate = new Zend_View_Helper_Translate($adapter);
print $translate-&gt;translate('simple'); // this returns 'einfach'
?&gt;</pre>
<p>
            You would use this way if you are not working with
            <code class="code">Zend_View</code> and need to create translated output.
        </p>
</div>
</div>
<br class="example-break"><p>
        As already seen, the <code class="code">translate()</code> method is used to return
        the translation. Just call it with the needed messageid of your
        translation adapter. But it can also replace parameters within the
        translation string. Therefore, it accepts variable parameters in two ways:
        either as a list of parameters, or as an array of parameters. As examples:
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.parameter"></a><p class="title"><b>Example 48.22. Single parameter</b></p>
<div class="example-contents">
<p>
            To use a single parameter just add it to the method.
        </p>
<pre class="programlisting">&lt;?php
// within your view
$date = "Monday";
$this-&gt;translate("Today is %1\$s", $date);
// could return 'Heute ist Monday'
?&gt;</pre>
</div>
</div>
<br class="example-break"><div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            Keep in mind that if you are using parameters which are also text,
            you may also need to translate these parameters.
        </p></td></tr>
</table></div>
<div class="example">
<a name="zend.view.helpers.initial.translate.parameterlist"></a><p class="title"><b>Example 48.23. List of parameters</b></p>
<div class="example-contents">
<p>
            Or use a list of parameters and add it to the method.
        </p>
<pre class="programlisting">&lt;?php
// within your view
$date = "Monday";
$month = "April";
$time = "11:20:55";
$this-&gt;translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date, $month, $time);
// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
?&gt;</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="zend.view.helpers.initial.translate.parameterarray"></a><p class="title"><b>Example 48.24. Array of parameters</b></p>
<div class="example-contents">
<p>
            Or use an array of parameters and add it to the method.
        </p>
<pre class="programlisting">&lt;?php
// within your view
$date = array("Monday", "April", "11:20:55");
$this-&gt;translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
?&gt;</pre>
</div>
</div>
<br class="example-break"><p>
        Sometimes it is necessary to change the locale of the translation. This
        can be done either dynamically per translation or statically for all
        following translations. And you can use it with both a parameter list
        and an array of parameters. In both cases the locale must be given as
        the last single parameter.
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.dynamic"></a><p class="title"><b>Example 48.25. Change locale dynamically</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
// within your view
$date = array("Monday", "April", "11:20:55");
$this-&gt;translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date, 'it');
?&gt;</pre></div>
</div>
<br class="example-break"><p>
        This example returns the Italian translation for the messageid. But it
        will only be used once. The next translation will use the locale from
        the adapter. Normally you will set the desired locale within the
        translation adapter before you add it to the registry. But you can also
        set the locale from within the helper:
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.static"></a><p class="title"><b>Example 48.26. Change locale statically</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
// within your view
$date = array("Monday", "April", "11:20:55");
$this-&gt;translate()-&gt;setLocale('it');
$this-&gt;translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
?&gt;</pre></div>
</div>
<br class="example-break"><p>
        The above example sets <code class="code">'it'</code> as the new default locale which
        will be used for all further translations.
    </p>
<p>
        Of course there is also a <code class="code">getLocale()</code> method to get the
        currently set locale. 
    </p>
<div class="example">
<a name="zend.view.helpers.initial.translate.getlocale"></a><p class="title"><b>Example 48.27. Get the currently set locale</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
// within your view
$date = array("Monday", "April", "11:20:55");

// returns 'de' as set default locale from our above examples
$this-&gt;translate()-&gt;getLocale();

$this-&gt;translate()-&gt;setLocale('it');
$this-&gt;translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);

// returns 'it' as new set default locale
$this-&gt;translate()-&gt;getLocale();
?&gt;</pre></div>
</div>
<br class="example-break">
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.view.helpers.paths"></a>48.4.2. Helper Paths</h3></div></div></div>
<p>
            As with view scripts, your controller can specify a stack of paths
            for <code class="code">Zend_View</code> to search for helper classes. By default,
            <code class="code">Zend_View</code> looks in "Zend/View/Helper/*" for helper
            classes. You can tell <code class="code">Zend_View</code> to look in other
            locations using the <code class="code">setHelperPath()</code> and
            <code class="code">addHelperPath()</code> methods.  Additionally, you can
            indicate a class prefix to use for helpers in the path provided, to
            allow namespacing your helper classes. By default, if no class
            prefix is provided, 'Zend_View_Helper_' is assumed.
        </p>
<pre class="programlisting">&lt;?php
$view = new Zend_View();

// Set path to /path/to/more/helpers, with prefix 'My_View_Helper'
$view-&gt;setHelperPath('/path/to/more/helpers', 'My_View_Helper');
        </pre>
<p>
            In fact, you can "stack" paths using the
            <code class="code">addHelperPath()</code> method. As you add paths to the stack,
            <code class="code">Zend_View</code> will look at the most-recently-added path for
            the requested helper class.  This allows you to add to (or even
            override) the initial distribution of helpers with your own custom
            helpers.
        </p>
<pre class="programlisting">&lt;?php
$view = new Zend_View();
// Add /path/to/some/helpers with class prefix 'My_View_Helper'
$view-&gt;addHelperPath('/path/to/some/helpers', 'My_View_Helper');
// Add /other/path/to/helpers with class prefix 'Your_View_Helper'
$view-&gt;addHelperPath('/other/path/to/helpers', 'Your_View_Helper');

// now when you call $this-&gt;helperName(), Zend_View will look first for
// "/path/to/some/helpers/HelperName" using class name "Your_View_Helper_HelperName",
// then for "/other/path/to/helpers/HelperName.php" using class name "My_View_Helper_HelperName",
// and finally for "Zend/View/Helper/HelperName.php" using class name "Zend_View_Helper_HelperName".
        </pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.view.helpers.custom"></a>48.4.3. Writing Custom Helpers</h3></div></div></div>
<p>
            Writing custom helpers is easy; just follow these rules:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                The class name must, at the very minimum, end with the helper
                name itself, using MixedCaps.  E.g., if you were writing a
                helper called "specialPurpose", the class name would minimally
                need to be "SpecialPurpose". You may, and should, give the class
                name a prefix, and it is recommended that you use 'View_Helper'
                as part of that prefix: "My_View_Helper_SpecialPurpose". (You
                will need to pass in the prefix, with or without the trailing
                underscore, to <code class="code">addHelperPath()</code> or
                <code class="code">setHelperPath()</code>).
            </p></li>
<li><p>
                The class must have a public method that matches the
                helper name; this is the method that will be called when
                your template calls "$this-&gt;specialPurpose()".  In our
                "specialPurpose" helper example, the required method
                declaration would be "public function specialPurpose()".
            </p></li>
<li><p>
                In general, the class should not echo or print or otherwise
                generate output.  Instead, it should return values to be
                printed or echoed.  The returned values should be escaped
                appropriately.
            </p></li>
<li><p>
                The class must be in a file named after the helper class.  Again
                using our "specialPurpose" helper example, the file has to be
                named "SpecialPurpose.php".
            </p></li>
</ul></div>
<p>
            Place the helper class file somewhere in your helper path stack, and
            <code class="code">Zend_View</code> will automatically load, instantiate,
            persist, and execute it for you.
        </p>
<p>
            Here is an example of our <code class="code">SpecialPurpose</code> helper code:
        </p>
<pre class="programlisting">&lt;?php
class My_View_Helper_SpecialPurpose
{
    protected $_count = 0;
    public function specialPurpose()
    {
        $this-&gt;_count++;
        $output = "I have seen 'The Jerk' {$this-&gt;_count} time(s).";
        return htmlspecialchars($output);
    }
}
        </pre>
<p>
            Then in a view script, you can call the <code class="code">SpecialPurpose</code>
            helper as many times as you like; it will be instantiated once, and
            then it persists for the life of that <code class="code">Zend_View</code>
            instance.
        </p>
<pre class="programlisting">&lt;?php
// remember, in a view script, $this refers to the Zend_View instance.
echo $this-&gt;specialPurpose();
echo $this-&gt;specialPurpose();
echo $this-&gt;specialPurpose();
        </pre>
<p>
            The output would look something like this:
        </p>
<pre class="programlisting">I have seen 'The Jerk' 1 time(s).
I have seen 'The Jerk' 2 time(s).
I have seen 'The Jerk' 3 time(s).
        </pre>
<p>
            Sometimes you will need access to the calling <code class="code">Zend_View</code>
            object -- for instance, if you need to use the registered encoding,
            or want to render another view script as part of your helper. To get
            access to the view object, your helper class should have a
            <code class="code">setView($view)</code> method, like the following:
        </p>
<pre class="programlisting">&lt;?php
class My_View_Helper_ScriptPath
{
    public $view;

    public function setView(Zend_View_Interface $view)
    {
        $this-&gt;view = $view;
    }

    public function scriptPath($script)
    {
        return $this-&gt;view-&gt;getScriptPath($script);
    }
}
        </pre>
<p>
            If your helper class has a <code class="code">setView()</code> method, it will be
            called when the helper class is first instantiated, and passed the
            current view object. It is up to you to persist the object in your
            class, as well as determine how it should be accessed.
        </p>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.view.scripts.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.view.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.view.abstract.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">48.3. View Scripts </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 48.5. Zend_View_Abstract</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
